<!DOCTYPE html>

<html lang="en" data-content_root="../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <title>cmake-cxxmodules(7) &mdash; CMake 4.1.1 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=a2c47e09" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css?v=4d06bd55" />
    
    <script src="../_static/documentation_options.js?v=e6a937a4"></script>
    <script src="../_static/doctools.js?v=9bcbadda"></script>
    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="cmake-developer(7)" href="cmake-developer.7.html" />
    <link rel="prev" title="cmake-configure-log(7)" href="cmake-configure-log.7.html" />
 

  </head><body>
    <input id="sidebar-check" type="checkbox" />
    <label id="sidebar-overlay" for="sidebar-check"></label>



    <div class="related relbar1" role="navigation" aria-label="Related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="cmake-developer.7.html" title="cmake-developer(7)"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="cmake-configure-log.7.html" title="cmake-configure-log(7)"
             accesskey="P">previous</a> |</li>
  <li>
    <label class="sidebar-toggle" for="sidebar-check"></label>
  </li>
  <li class="rootlink">
    <img src="../_static/cmake-logo-16.png" width="16" height="16" alt=""/>
    <a href="https://cmake.org/">CMake 4.1.1</a>
    <span class="reldelim1"> &#187;</span>
  </li>
  <li>
    <a href="../index.html">Documentation</a> &#187;
  </li>

        <li class="nav-item nav-item-this"><a href="">cmake-cxxmodules(7)</a></li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <span class="target" id="manual:cmake-cxxmodules(7)"></span><section id="cmake-cxxmodules-7">
<h1>cmake-cxxmodules(7)<a class="headerlink" href="#cmake-cxxmodules-7" title="Link to this heading">¶</a></h1>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.28.</span></p>
</div>
<p>C++ 20 introduced the concept of &quot;modules&quot; to the language.  The design
requires build systems to order compilations among each other to satisfy
<code class="docutils literal notranslate"><span class="pre">import</span></code> statements reliably.  CMake's implementation asks the compiler
to scan source files for module dependencies during the build, collates
scanning results to infer ordering constraints, and tells the build tool
how to dynamically update the build graph.</p>
<section id="compilation-strategy">
<h2>Compilation Strategy<a class="headerlink" href="#compilation-strategy" title="Link to this heading">¶</a></h2>
<p>With C++ modules, compiling a set of C++ sources is no longer embarrassingly
parallel. That is, any given source may first require the compilation of
another source file first in order to provide a &quot;CMI&quot; (compiled module
interface) or &quot;BMI&quot; (binary module interface) that C++ compilers use to
satisfy <code class="docutils literal notranslate"><span class="pre">import</span></code> statements in other sources. With headers, sources could
share their declarations so that any consumers could compile independently.
With modules, declarations are now generated into these BMI files by the
compiler during compilation based on the contents of the source file and its
<code class="docutils literal notranslate"><span class="pre">export</span></code> statements.</p>
<p>The order necessary for compilation requires build-time resolution of the
ordering because the order is controlled by the contents of the sources. This
means that the ordering needs extracted from the source during the build to
avoid regenerating the build graph via a configure and generate phase for
every source change to get a correct build.</p>
<p>The general strategy is to use a &quot;scanner&quot; to extract the ordering dependency
information and update the build graph with new edges between existing edges
by taking the per-source scan results (represented by <a class="reference external" href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html">P1689R5</a> files) and
&quot;collating&quot; the dependencies within a target and to modules produced by
targets visible to the target. The primary task is to generate &quot;module map&quot;
files to pass to each compile rule with the paths to the BMIs needed to
satisfy <code class="docutils literal notranslate"><span class="pre">import</span></code> statements. The collator also has tasks to use the
build-time information to fill out information including <code class="docutils literal notranslate"><span class="pre">install</span></code> rules for
the module interface units, their BMIs, and properties for any exported
targets with C++ modules.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>CMake is focusing on correct builds before looking at performance
improvements. There are known tactics within the chosen strategy which may
offer build performance improvements. However, they are being deferred
until we have a working model against which to compare them. It is also
important to note that a tactic useful in one situation (e.g., clean
builds) may not be performant in a different situation (e.g., incremental
builds). Finding a balance and offering controls to select the tactics is
future work.</p>
</div>
</section>
<section id="scanning-control">
<h2>Scanning Control<a class="headerlink" href="#scanning-control" title="Link to this heading">¶</a></h2>
<p>Whether or not sources get scanned for C++ module usage is dependent on the
following queries. The first query that provides a yes/no answer is used.</p>
<ul class="simple">
<li><p>If the source file belongs to a file set of type <code class="docutils literal notranslate"><span class="pre">CXX_MODULES</span></code>, it will
be scanned.</p></li>
<li><p>If the target does not use at least C++ 20, it will not be scanned.</p></li>
<li><p>If the source file is not the language <code class="docutils literal notranslate"><span class="pre">CXX</span></code>, it will not be scanned.</p></li>
<li><p>If the <span class="target" id="index-0-prop_sf:CXX_SCAN_FOR_MODULES"></span><a class="reference internal" href="../prop_sf/CXX_SCAN_FOR_MODULES.html#prop_sf:CXX_SCAN_FOR_MODULES" title="CXX_SCAN_FOR_MODULES"><code class="xref cmake cmake-prop_sf docutils literal notranslate"><span class="pre">CXX_SCAN_FOR_MODULES</span></code></a> source file property is set, its
value will be used.</p></li>
<li><p>If the <span class="target" id="index-0-prop_tgt:CXX_SCAN_FOR_MODULES"></span><a class="reference internal" href="../prop_tgt/CXX_SCAN_FOR_MODULES.html#prop_tgt:CXX_SCAN_FOR_MODULES" title="CXX_SCAN_FOR_MODULES"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">CXX_SCAN_FOR_MODULES</span></code></a> target property is set, its value
will be used.  Set the <span class="target" id="index-0-variable:CMAKE_CXX_SCAN_FOR_MODULES"></span><a class="reference internal" href="../variable/CMAKE_CXX_SCAN_FOR_MODULES.html#variable:CMAKE_CXX_SCAN_FOR_MODULES" title="CMAKE_CXX_SCAN_FOR_MODULES"><code class="xref cmake cmake-variable docutils literal notranslate"><span class="pre">CMAKE_CXX_SCAN_FOR_MODULES</span></code></a> variable
to initialize this property on all targets as they are created.</p></li>
<li><p>Otherwise, the source file will be scanned if the compiler and generator
support scanning.  See policy <span class="target" id="index-0-policy:CMP0155"></span><a class="reference internal" href="../policy/CMP0155.html#policy:CMP0155" title="CMP0155"><code class="xref cmake cmake-policy docutils literal notranslate"><span class="pre">CMP0155</span></code></a>.</p></li>
</ul>
<p>Note that any scanned source will be excluded from any unity build (see
<span class="target" id="index-0-prop_tgt:UNITY_BUILD"></span><a class="reference internal" href="../prop_tgt/UNITY_BUILD.html#prop_tgt:UNITY_BUILD" title="UNITY_BUILD"><code class="xref cmake cmake-prop_tgt docutils literal notranslate"><span class="pre">UNITY_BUILD</span></code></a>) because module-related statements can only happen at
one place within a C++ translation unit.</p>
</section>
<section id="compiler-support">
<h2>Compiler Support<a class="headerlink" href="#compiler-support" title="Link to this heading">¶</a></h2>
<p>Compilers which CMake natively supports module dependency scanning include:</p>
<ul class="simple">
<li><p>MSVC toolset 14.34 and newer (provided with Visual Studio 17.4 and newer)</p></li>
<li><p>LLVM/Clang 16.0 and newer</p></li>
<li><p>GCC 14 (for the in-development branch, after 2023-09-20) and newer</p></li>
</ul>
</section>
<section id="import-std-support">
<h2><code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">std</span></code> Support<a class="headerlink" href="#import-std-support" title="Link to this heading">¶</a></h2>
<p>Support for <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">std</span></code> is limited to the following toolchain and standard
library combinations:</p>
<ul class="simple">
<li><p>Clang 18.1.2 and newer with <code class="docutils literal notranslate"><span class="pre">-stdlib=libc++</span></code> or <code class="docutils literal notranslate"><span class="pre">-stdlib=libstdc++</span></code></p></li>
<li><p>MSVC toolset 14.36 and newer (provided with Visual Studio 17.6 Preview 2 and
newer)</p></li>
<li><p>GCC 15 and newer.</p></li>
</ul>
<p>The <span class="target" id="index-0-variable:CMAKE_CXX_COMPILER_IMPORT_STD"></span><a class="reference internal" href="../variable/CMAKE_CXX_COMPILER_IMPORT_STD.html#variable:CMAKE_CXX_COMPILER_IMPORT_STD" title="CMAKE_CXX_COMPILER_IMPORT_STD"><code class="xref cmake cmake-variable docutils literal notranslate"><span class="pre">CMAKE_CXX_COMPILER_IMPORT_STD</span></code></a> variable may be used to detect
support for a standard level with the active C++ toolchain.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This support is provided only when experimental support for
<code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">std;</span></code> has been enabled by the
<code class="docutils literal notranslate"><span class="pre">CMAKE_EXPERIMENTAL_CXX_IMPORT_STD</span></code> gate.</p>
</div>
</section>
<section id="generator-support">
<h2>Generator Support<a class="headerlink" href="#generator-support" title="Link to this heading">¶</a></h2>
<p>The list of generators which support scanning sources for C++ modules include:</p>
<ul class="simple">
<li><p><span class="target" id="index-0-generator:Ninja"></span><a class="reference internal" href="../generator/Ninja.html#generator:Ninja" title="Ninja"><code class="xref cmake cmake-generator docutils literal notranslate"><span class="pre">Ninja</span></code></a></p></li>
<li><p><span class="target" id="index-0-generator:Ninja Multi-Config"></span><a class="reference internal" href="../generator/Ninja%20Multi-Config.html#generator:Ninja Multi-Config" title="Ninja Multi-Config"><code class="xref cmake cmake-generator docutils literal notranslate"><span class="pre">Ninja</span> <span class="pre">Multi-Config</span></code></a></p></li>
<li><p><span class="target" id="index-0-generator:Visual Studio 17 2022"></span><a class="reference internal" href="../generator/Visual%20Studio%2017%202022.html#generator:Visual Studio 17 2022" title="Visual Studio 17 2022"><code class="xref cmake cmake-generator docutils literal notranslate"><span class="pre">Visual</span> <span class="pre">Studio</span> <span class="pre">17</span> <span class="pre">2022</span></code></a></p></li>
</ul>
<section id="limitations">
<h3>Limitations<a class="headerlink" href="#limitations" title="Link to this heading">¶</a></h3>
<p>There are a number of known limitations of the current C++ module support in
CMake.  This does not document known limitations or bugs in compilers as these
can change over time.</p>
<p>For all generators:</p>
<ul class="simple">
<li><p>Header units are not supported.</p></li>
<li><p>No builtin support for <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">std;</span></code> or other compiler-provided modules.</p></li>
</ul>
<p>For the Ninja Generators:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">ninja</span></code> 1.11 or newer is required.</p></li>
</ul>
<p>For the <a class="reference internal" href="cmake-generators.7.html#visual-studio-generators"><span class="std std-ref">Visual Studio Generators</span></a>:</p>
<ul class="simple">
<li><p>Only Visual Studio 2022 and MSVC toolsets 14.34 (Visual Studio
17.4) and newer.</p></li>
<li><p>No support for exporting or installing BMI or module information.</p></li>
<li><p>No support for compiling BMIs from <code class="docutils literal notranslate"><span class="pre">IMPORTED</span></code> targets with C++ modules
(including <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">std</span></code>).</p></li>
<li><p>No diagnosis of using modules provided by <code class="docutils literal notranslate"><span class="pre">PRIVATE</span></code> sources from
<code class="docutils literal notranslate"><span class="pre">PUBLIC</span></code> module sources.</p></li>
</ul>
</section>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper">
  <div>
    <h3>Table of Contents</h3>
    <ul>
<li><a class="reference internal" href="#">cmake-cxxmodules(7)</a><ul>
<li><a class="reference internal" href="#compilation-strategy">Compilation Strategy</a></li>
<li><a class="reference internal" href="#scanning-control">Scanning Control</a></li>
<li><a class="reference internal" href="#compiler-support">Compiler Support</a></li>
<li><a class="reference internal" href="#import-std-support"><code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">std</span></code> Support</a></li>
<li><a class="reference internal" href="#generator-support">Generator Support</a><ul>
<li><a class="reference internal" href="#limitations">Limitations</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  </div>
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="cmake-configure-log.7.html"
                          title="previous chapter">cmake-configure-log(7)</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="cmake-developer.7.html"
                          title="next chapter">cmake-developer(7)</a></p>
  </div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../_sources/manual/cmake-cxxmodules.7.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<search id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="Related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="cmake-developer.7.html" title="cmake-developer(7)"
             >next</a> |</li>
        <li class="right" >
          <a href="cmake-configure-log.7.html" title="cmake-configure-log(7)"
             >previous</a> |</li>
  <li>
    <label class="sidebar-toggle" for="sidebar-check"></label>
  </li>
  <li class="rootlink">
    <img src="../_static/cmake-logo-16.png" width="16" height="16" alt=""/>
    <a href="https://cmake.org/">CMake 4.1.1</a>
    <span class="reldelim1"> &#187;</span>
  </li>
  <li>
    <a href="../index.html">Documentation</a> &#187;
  </li>

        <li class="nav-item nav-item-this"><a href="">cmake-cxxmodules(7)</a></li> 
      </ul>
    </div>

    <div class="footer" role="contentinfo">
    &#169; Copyright 2000-2025 Kitware, Inc. and Contributors.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.1.3.
    </div>
<script type="text/javascript">
(function() {
  "use strict";
  const hide = () => document.getElementById("sidebar-check").checked = false;
  addEventListener("keydown", e => (e.key === "Escape") && hide());
  addEventListener("click", e => (e.target.tagName === "A") && hide());
  addEventListener("hashchange", hide)
})();
</script>
  </body>
</html>